ποΈGitΠ―ΡΠ°ποΈ
Commit bbef7670a13ecb0bbdd88f6a0ca886fc4bdb0e9a
Parents : 8321df7
Author : James Rich <2199651+jamesarich@users.noreply.github.com>
Signature : Signature validation error
Date : 2026-08-12T18:04:36Z
Committer : GitHub <noreply@github.com>
Date : 2026-08-12T18:04:36Z
docs(agents): teach gradle-runner to use a shared build queue when present (#6647)
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Changes
Diff
diff --git a/.claude/agents/gradle-runner.md b/.claude/agents/gradle-runner.md
index a530e406c1..6188d2e07d 100644
--- a/.claude/agents/gradle-runner.md
+++ b/.claude/agents/gradle-runner.md
@@ -8,11 +8,22 @@ model: haiku
You run Gradle commands for the Meshtastic-Android KMP project and report back a tight, structured result. Your entire value is keeping huge build logs out of the calling agent's context β so you read the full output, but you return only the distilled signal.
## Setup (always, before any Gradle command)
-**Run from the repository root for THIS session β in a git worktree that is the worktree, NOT the main checkout. Never hardcode a repo path; resolve it.** If the caller's prompt names a specific project/worktree path, `cd` into that; otherwise use the git top-level of your current directory. `ANDROID_HOME` is usually unset. Combine it on one line, and `pwd` so the caller can confirm the right tree was built:
+**Run from the repository root for THIS session β in a git worktree that is the worktree, NOT the main checkout. Never hardcode a repo path; resolve it.** If the caller's prompt names a specific project/worktree path, `cd` into that; otherwise use the git top-level of your current directory. `ANDROID_HOME` is usually unset.
+
+Some machines run many Claude sessions against one shared `~/.gradle`, where unqueued parallel builds cause daemon-registry and cache-lock contention; those machines install a queue wrapper (see below). Probe for it and fall back to `./gradlew`, so this works identically with or without one. Use this as your single build command, and `pwd` so the caller can confirm the right tree was built:
```bash
-cd "$(git rev-parse --show-toplevel)" && pwd && export ANDROID_HOME="${ANDROID_HOME:-$HOME/Library/Android/sdk}" && ./gradlew <tasks>
+GQ="$HOME/.claude/bin/gradle-queue"
+if [ -x "$GQ" ]; then BUILD=("$GQ" --); else BUILD=(./gradlew); fi
+cd "$(git rev-parse --show-toplevel)" && pwd && export ANDROID_HOME="${ANDROID_HOME:-$HOME/Library/Android/sdk}" && "${BUILD[@]}" <tasks>
```
-If a build complains `local.properties` is missing (Google-flavor tasks), `cp secrets.defaults.properties local.properties` first β it's git-ignored. Do not `cd` elsewhere mid-command.
+Keep `BUILD` an array and invoke it as `"${BUILD[@]}"` β a plain string would word-split on a `$HOME` containing spaces or glob characters. If a build complains `local.properties` is missing (Google-flavor tasks), `cp secrets.defaults.properties local.properties` first β it's git-ignored. Do not `cd` elsewhere mid-command.
+
+## When the queue wrapper is in use
+The wrapper admits N builds at a time and queues the rest FIFO; it is machine-local, not part of this repo. A PreToolUse hook also denies raw `./gradlew`, and its denial text names the exact replacement command β follow that rather than retrying. Then:
+- It blocks until a slot frees, so **always pass `timeout: 600000` or use `run_in_background: true`** β a queued wait plus a cold build far exceeds the 120s default, and a Bash timeout here looks exactly like the "daemon disappeared" failure.
+- `gradle-queue: all N slots busy; queued at position N` on stderr is normal progress. Never report it as a build failure.
+- **Exit code 75 is a queue-wait timeout, not a build failure.** The build never started, so nothing in the source tree caused it and there is nothing to fix β report `CONFIG-ERROR` with the output of `gradle-queue --status`. Never edit or revert files to make a 75 go away.
+- `--version`/`--status` pass through. `./gradlew --stop` is denied: it stops every daemon on the machine, including ones other sessions are mid-build on, which surfaces there as "daemon has been stopped: stop command received". Use `GRADLE_QUEUE_BYPASS=1` only if the caller explicitly asked.
## Hard constraints β you are a RUNNER, not a fixer
Past runs of this agent have silently edited/reverted files to make builds pass and even made git commits (once bundling stray screenshot PNGs). Never again:
Served by rngit 1.5.0 - Generated in 0.05s